# 文档沉淀和知识管理 > 记录下来，才能走得更远 大家好，我是鱼皮。 先分享一个我的小故事。我大二的时候跟队做过一个项目，随着个人给项目编写的代码越来越多，开始慢慢主导起这个项目，直到最后整个项目的逻辑我都烂熟于心，团队同学遇到问题都会来问我。 但是，由于个人时间原因，后来我退队不干了，把代码给其他同学认真讲了一遍。 结果你猜怎么着？ 在我退队后，隔三差五就会有队内的同学来问我关于这个项目的问题。更离谱的是，一个月后，这个项目倒闭了！ 当我后来问其他同学为啥项目会倒闭的时候，人家没好气的说：你这家伙不写文档，项目好多地方都看不懂，没法做下去了。 这时我才意识到：自己一直专注于给项目写代码，但是却忘了把自己的经验、项目的信息记录下来，同步给其他同学，导致我负责的部分基本没人能接手。 唉，那会儿还是经验太少了。在那之后，我做任何项目的时候，都会写文档。哪怕不为别人，起码保证自己能看懂自己之前写的项目。 这也是本文要分享的核心 —— **文档沉淀**。无论是个人还是团队，无论是在学习、工作、还是项目中，无论对程序员、产品经理、还是项目管理者，做好文档沉淀都是至关重要的。 下面我会给大家依次分享：为什么要写文档？怎么写出好文档？怎么管理好文档？ ## 什么是文档？ 文档是记录、储存和传递信息的载体。 我们的项目需求表、系统的设计方案、某某调研报告、某次会议记录、解决过的 Bug，甚至是学某个视频教程时随手记录的笔记，都是文档。 ## 为什么要写文档？ 从文档的定义出发，我们就已经能意识到文档的基本作用了。 - 记录信息：收集临时的信息 - 储存信息：防止信息丢失和遗忘 - 传递信息：把信息和他人共享 我们的人脑容量有限，不可能记忆所有信息，而写文档，本质上就是在打造属于我们的第二大脑。 像我的脑容量是比较小的，所以我有随手记录、随手写文档的习惯，有的时候走在路上有个好点子都立刻掏出手机记下来。 ### 文档对项目的价值 而对于做项目（尤其是企业大项目），文档又有更进一步的价值。 在项目初期，文档具有指导整个项目顺利推进的意义。如果将做项目比作盖摩天大楼，那么文档就是大楼的蓝图。没有蓝图，建筑工人只能盲目工作，能不能完成都很难说，更别提保证大楼的质量和安全了。 同样，在项目初期不写文档、没有系统的方案和执行计划，团队成员在开发过程中就会迷失方向，会经常出现延期、完不成、返工的情况。 > 看过我直播的同学应该知道，每个项目开始，我都会在文档上编写需求分析、方案设计、技术选型等内容。在做具体功能前，也是先在文档上写好设计实现方案，然后才去写代码。虽然写文档的过程会多花一点时间，但是会大幅降低整个项目的工时。 在项目中期，文档的意义是 **持续** 记录和追踪项目的状态，让信息在团队间公开透明，从而做出正确的选择、即时规避风险。 打个比方，把做项目当成跑马拉松，文档就是沿途的路标，会告诉大家跑到哪里了、接下来怎么跑；而如果前方有危险，路标也会给大家警示。如果没有文档，大家很快就跑散了，各自为战；一个人遭遇了风险，可能会拖垮整个团队。 在项目后期，文档的意义是帮助我们复盘总结、持续维护项目以及知识传承。 - 复盘总结：通过阅读文档，我们能够回顾整个项目从诞生到结束的完整过程，从而分析出该项目成功或失败的原因，便于我们从中吸取经验，助力下一个项目的成功。 - 持续维护项目：如果这是一个需要持续维护和更新的项目，有了文档（比如 Bug 手册、用户手册），项目出现问题时，哪怕换了一位项目维护者，也能很快地从文档中找到解决方案，不会出现 “一人离职、项目倒闭” 的情况。 - 知识传承：沉淀好的文档，是前人宝贵的经验、教训、思路和方法汇总，非常值得学习，未来能给更多团队的同学带来启发和收获。 总之，写文档是一件利人利己的事，每写一个字，都是在生产价值。 --- 在理解了文档的重要性后，我们应该怎么做好文档沉淀呢？ 这里我们把文档沉淀进行拆分，需要做好两件事： 1. 写出好文档（这是前提） 2. 管理好文档 下面我们分别讲解。 ## 怎么写出好文档？ 想要写出好的文档，我们要先了解 “什么是好文档”，然后再去学习写文档的工具和方法。 ### 什么是好文档？ 我自己评判文档好坏的几个标准： 1）人能看懂、易于理解的 首先，你的文档是给 **人** 看的，如果是自己记录学习笔记，那么首先要保证自己能看懂；如果是在团队内共享文档，那么要保证别人能理解。如果本来一句话就能说清楚的内容，你在文档上用 20 句话来解释，这样哪怕你写了文档，别人可能还是直接来麻烦你本人。 2）结构清晰、易于查找的 好的文档，应该是别人从上到下扫一遍，就知道你在写什么、你想表达什么、我能从你的文档中得到什么、我在哪能找到我需要的内容。 就像这篇文章一样，我用了多级标题来划分文章的结构，你能直接通过目录大纲快速定位感兴趣的内容进行阅读。 3）内容完整、表述准确的 好的文档就像是项目中的一个模块，它应该是完整的、高内聚的，让人仅通过这个文档，就能解决自己的问题。 比如《某 Java Bug 的解决方案》文档，应该把 Bug 的起因、分析排查过程、解决方案、经验总结全部写出来。而不是说把这个 Bug 抛出来，怎么解决我不说~ 哎，就是玩~ 另外，文档中的一些词汇和语句的表述一定要尽量准确，不能有歧义！ 比如我们鱼聪明 AI 在最初评估成本时，写的是 “服务器若干、价格累积万元左右”，“若干” 和 “万元左右” 其实都是比较模糊的词汇，类似的情况多了就可能导致成本计算错误而亏损。后面我们把上述词汇改成了类似 “服务器 4C 8G 1 台，价格 1000 元 / 月”，实现更精细化的成本控制。 此外，好文档还可能有其他的标准，比如面向用户的产品文档，应该保证文档整体的风格、排版一致，给读者带来最佳的体验。文档写得好，也会提升用户对团队的认可度，从而更愿意使用团队的产品。 ### 写作工具 工欲善其事必先利其器，在介绍写好文档的方法前，先分享一些写作工具。 多年以前，写文档基本都是用 Word，但 Word 其实是有很多的问题和不足的。比如要自己手动调整格式、同一份 Word 文档由于兼容性问题在另一个电脑上打不开或者排版错乱等等。 所以现在我强烈推荐大家学习 Markdown（一种轻量级标记语言），可以让你用同一套语法轻松编写出排版、格式一致的代码。 比如用 “## 二级标题” 来表示二级标题，用 “> 引用” 来表示引用文案等。 现在很多编辑器软件都支持 Markdown，比如我们平时用的 VS Code、JetBrains 全家桶。但如果要选择一个体验最好的本地 Markdown 编辑器，我推荐大家使用 Typora，这也是自己用了多年的软件。 在写文档的过程中，也经常需要一些绘图来辅助理解，比如流程图、架构图等等，可以使用在线工具 Draw.io、经典软件 Visio 等。如果需要绘制思维导图，可以使用 XMind。如果要生成一些配图，可以使用目前很火的 Midjourney（或者我们的鱼聪明 AI）。 如果你需要把文档发到其他自媒体平台，可以直接把 Markdown 内容复制粘贴到 mdnice 网站中，它会自动帮你生成精美排版的文章。 此外，随着 web 前端技术的发展，线上文档写作网站也越来越强大，如果要团队协作、实时共享文档的话，可以选用语雀知识库、腾讯文档、飞书文档等工具。 ### 方法 #### “抄” 首先，想写好文档，要做的第一件事是 “抄”。 哦不，读书人的事，应该叫 “学习借鉴”。 如果你不会写文档，比如项目文档、设计文档、用户手册，怎么办？ 很简单，到网上找优秀的 **成品** ，去模仿。 不单单是写文档，做自媒体、做产品、写论文、学手艺，你想做好任何事情，第一件事都应该是：看看别人怎么做的，向别人学习。 - 你要开发网站，就去网上找现成的网站 - 你要做视频，就去网上找爆款视频 这是最简单的道理，很多东西都有前人做过，所以哪怕别人不分享教程，只要你去模仿，用点心也能完成。 再加上现在开源文化盛行，很多项目和文档都在 GitHub 等平台公开可见。当你要写一个文档时，直接先复制一下知名项目的 README.md 文件，然后把原本的目录大纲保留，把内容换成自己的，就得到了一份很标准的文档，就这么简单。 等你阅读和编写的文档多了，自然也能形成一套属于自己（团队）的写文档方法。 #### 写作流程化 很多人讨厌写文档，就是因为感觉没有思路、无从下笔、完全不知道写什么。 我以前也常常是新建一个空白文档，然后对着它发呆。。。 但后来随着写作次数越来越多，我也修得了一套能够快速写出内容的方法，我把它称为 “写作流程化”。 什么叫流程？你去食堂买早饭，先排队、再买包子、再打豆浆、再找座位，这就是一个刻在 DNA 里的流程。 如果你也能有一套明确的写作流程，那么写作就像你买早饭一样简单。 具体怎么做呢？ 1）先想清楚文章的结构，根据主题写出大纲 比如我在写这篇文章时，先写了 “什么是文档？为什么写文档？怎么写出好文档？怎么管理好文档？” 这几个小标题，把整篇文章的框架定下来。而不是从上到下漫无目的地去写，想到哪儿写到哪儿。 写大纲的过程本身就是在培养你的结构化思维 —— 把复杂的问题进行结构化拆解。如果你发现自己写大纲都很困难，那么不妨尝试把时间线作为大纲，按照由远及近的顺序，依次去写你各个时期的想法。 2）填空 只要确定了大纲，你就可以有 100% 的信息，这篇文章你必然能写完。因为剩下要做的就是往每个章节下填空就好了。 类似于有个导师给你规划好了你要做哪些事，你就有了个目标，更容易坚定地执行下去。 3）优化 写完大致的内容后，我们要整体读 2 - 3 遍文档，进行适当地优化。 就像我们写代码一样，虽然功能是完成了，但是代码可能写得比较烂，提交代码前得再改改。 列举一些常见的优化点： 1. 修改错别字 2. 小标题间增加关联语，承上启下，使内容更连贯 3. 重点前置，把文档的关键信息放到开头，吸引人阅读 4. 图文并茂、多用比喻，让文档更易于理解 这一套流程走下来，一篇完善的文档就诞生了。 #### 持续优化 无论是自己写学习笔记、还是项目文档、用户手册，都不是写完一版就结束了的。好的文档是需要持续优化迭代的，如果有人指出了问题或者文档内容有过期，应当即时修复处理。不然错误的文档不仅不能帮助到人，还会产生误导。 像我们在开发鱼聪明 AI 的过程中，就很不幸地参考了一篇胡说八道的过期文档，让本就不富裕的团队雪上加霜。 #### 积累 经常有朋友问我：鱼皮你平时又上班又高产胜母猪，怎么做到的？ 其实我有一个习惯，就是会把生活中觉得有趣的事、或者突然想到的灵感记录下来，每隔一段时间去整理一下，后来我惊喜地发现，有些碎片化的内容竟然可以串起来讲，组成一篇文章。 就像打游戏一样，你想刷的装备一直出不来，你不在乎的装备碎片反而攒了一大堆。结果有天，你发现碎片都能够合成完整的装备了，竟然还挺好用，这就是无心插柳柳成荫吧。 写文档也是，哪怕你无法写一篇全面系统的文档，在你工作中遇到 Bug 的时候，随手开个文档记录下来；再遇到 Bug 的时候，就再打开之前的文档记录下来。次数多了，稍加整理，一篇高质量的文档不就来了？ ### 举例 以我们的鱼聪明 AI 来举例，刚开始写项目立项文档时，按照上述的 “流程化” 方法，先定了文档大纲： 1. 为什么做？项目背景 2. 做什么？需求分析 3. 怎么做？设计方案 4. 具体怎么做？工作安排等等 然后才是一条一条地去补充完善，之后在每次开会和上线后，再持续更新完善一下这个文档。 完善文档的过程中，我也会看到很多之前记录的内容，提醒着自己在做这个项目的过程中不要走偏。 ## 怎么管理好文档？ 随着我们项目的不断迭代，文档数也越来越多、越来越零碎，怎么管理好这些文档，让大家需要阅读时能快速找到，这是个大问题。 尤其是对于大项目来说，假如 100 个人一起开发，每人写 10 篇文档就是 1000 篇文档，怎么对这 1000 篇文档进行管理呢？ 要先有一个意识：尽早发现问题，会比后期解决问题的成本要低很多。 所以管理好文档这件事，应该主要靠 “前期的策略” 和 “中期的持续优化”，而不是后面再去人工整理大量的文档。 > 代码屎山就是这么来的，烂代码堆得越多，越没人敢动。 所以首先，我们在开始项目前，就要建立好一套规范的 **文档体系** 。 1）文档线上化 只要是和项目 / 工作相关的文档，不要让大家在本地去写，而是直接用线上文档去 **实时协同** 。很简单的道理，你本地改了一段话，别人本地也改了相同文档的一句话，那最终以谁的为准？ 像我们鱼聪明 AI 的所有内部文档，都是使用语雀知识库来托管的，所有项目的信息在团队内部公开透明，从而尽最大地可能性消除信息差。 而且线上知识库还有一个好处，就是查找搜索方便，整个知识库的内容一键随便搜。 2）分组 随着文档或知识库越来越多，必然就会给大家的查找造成负担。所以我在 **最开始** 就给所有团队内部的知识库都按主题做了分组，如下图： ![](https://pic.yupi.icu/1/image-20230705134114445.png) 每个知识库下的文档，也建立了相应的分组： ![](https://pic.yupi.icu/1/image-20230705134325495.png) 当然，分组这个操作也是需要持续做的。如果刚开始没有办法预估会有哪些分组，那就等后面需要分组的时候，即时新建就好。 3）访问控制 所谓访问控制，就是让部分成员只能看到部分文档。这么做不仅是为了安全，也可以让大家尽量聚焦在自己的工作上，更能找到自己需要的文档。 目前我们鱼聪明 AI 团队的每个知识库都是有严格的访问控制的，只有大家需要看某个知识库时，我才会给他们开对应的权限。当然这也不是说要限制团队成员的学习，如果他对某个知识库感兴趣，可以直接申请查看。 主流的线上文档软件基本都支持访问控制和权限管理，实现上没有什么难度。 4）培养团队文档文化 还记得这篇文章开头我给大家讲的自己的故事么？有些人可能是没有写文档的意识、或者就是不爱写文档的！如果这个人又是项目的重要贡献者，那么他个人掌握的、团队不清楚的信息就会越来越多，最终就会出现 “他的代码别人动不了”、“他一走项目就完蛋” 的情况。 为了把这种风险扼杀在摇篮里，我反复跟团队的成员强调，一定要多写工作文档、即时同步信息，甚至对于一些重要的工作，我会把文档作为大家工作成果的一部分。慢慢地，大家就养成了写文档、文档分类的习惯。 --- ## 写在最后 文档沉淀是做好产品的重要一环。无论你是用 Vibe Coding 做个人项目，还是想做一款真正的产品，都要重视文档的编写和管理。 记住这几个关键点： 1. 文档是你的第二大脑，要随时记录 2. 好文档要易懂、结构清晰、内容完整 3. 学会使用 Markdown 和在线文档工具 4. 写文档要流程化：大纲 → 填空 → 优化 5. 文档要持续优化和积累 在 Vibe Coding 时代，AI 可以帮你写代码，但是项目的思路、设计方案、踩过的坑，这些都需要你自己记录下来。只有沉淀好文档，才能让项目走得更远。 加油，从今天开始养成写文档的好习惯！💪 ## 推荐资源 1）鱼皮 AI 导航网站：[AI 资源大全、最新 AI 资讯、免费 AI 教程](https://ai.codefather.cn) 2）编程导航学习圈：[学习路线、编程教程、实战项目、求职宝典、交流答疑](https://www.codefather.cn) 3）程序员面试八股文：[实习/校招/社招高频考点、企业真题解析](https://www.mianshiya.com) 4）程序员写简历神器：[专业模板、丰富例句、直通面试](https://www.laoyujianli.com) 5）1 对 1 模拟面试：[实习/校招/社招面试拿 Offer 必备](https://ai.mianshiya.com)